storyblok-js-client

What is storyblok-js-client?

The storyblok-js-client is a JavaScript client for interacting with the Storyblok API. It allows developers to easily manage content, perform CRUD operations, and interact with the Storyblok content delivery and management APIs.

What are storyblok-js-client's main functionalities?

Initialize the Client

This feature allows you to initialize the Storyblok client with your access token, which is required to authenticate and interact with the Storyblok API.

const StoryblokClient = require('storyblok-js-client');
const client = new StoryblokClient({
  accessToken: 'your-access-token'
});

Get a Story

This feature allows you to fetch a specific story from the Storyblok API. In this example, it fetches the 'home' story.

client.get('cdn/stories/home', {}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Create a Story

This feature allows you to create a new story in your Storyblok space. The example demonstrates creating a story with a name, slug, and content.

client.post('spaces/your-space-id/stories', {
  story: {
    name: 'New Story',
    slug: 'new-story',
    content: {
      component: 'page',
      body: []
    }
  }
}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Update a Story

This feature allows you to update an existing story in your Storyblok space. The example shows how to update the name, slug, and content of a story.

client.put('spaces/your-space-id/stories/your-story-id', {
  story: {
    name: 'Updated Story',
    slug: 'updated-story',
    content: {
      component: 'page',
      body: []
    }
  }
}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Delete a Story

This feature allows you to delete a story from your Storyblok space. The example demonstrates how to delete a story by its ID.

client.delete('spaces/your-space-id/stories/your-story-id').then(response => {
  console.log('Story deleted');
}).catch(error => {
  console.error(error);
});

Other packages similar to storyblok-js-client

contentful

Contentful is a content management platform that allows you to create, manage, and distribute content to any platform. It offers a JavaScript client similar to storyblok-js-client for interacting with its API. Contentful provides a more extensive set of features and integrations, but Storyblok is known for its visual editor and ease of use.

prismic-javascript

Prismic is a headless CMS that offers a JavaScript client for interacting with its API. It provides similar functionalities to storyblok-js-client, such as fetching and managing content. Prismic is known for its flexible content modeling and integration capabilities.

strapi-sdk-javascript

Strapi is an open-source headless CMS that provides a JavaScript SDK for interacting with its API. It offers similar functionalities to storyblok-js-client, including content management and CRUD operations. Strapi is highly customizable and can be self-hosted, providing more control over the CMS environment.

README

Universal JavaScript SDK for Storyblok's API

This client is a thin wrapper for the Storyblok API's to use in Node.js and the browser.

🚀 Usage

Install

# as axios is a peerDependency, you should install it too
npm install storyblok-js-client axios # yarn add storyblok-js-client axios

How to use it

Using the Content Deliver API

// 1. Require the Storyblok client
const StoryblokClient = require("storyblok-js-client");

// 2. Initialize the client with the preview token
// from your space dashboard at https://app.storyblok.com
let Storyblok = new StoryblokClient({
  accessToken: "xf5dRMMjltLzKOcNgMaU9Att",
});

Using the Content Deliver API for US region

You should use the space access token AND region: 'us' whenever your space was created under US Server Location.

let Storyblok = new StoryblokClient({
  accessToken: "xf5dRMMjltLzKOcNgMaU9Att",
  region: 'us' // if US server
});

Using the Content Management API

// 1. Require the Storyblok client
const StoryblokClient = require("storyblok-js-client");
const spaceId = 12345;

// 2. Initialize the client with the oauth token
// from the my account area at https://app.storyblok.com
let Storyblok = new StoryblokClient({
  oauthToken: "YOUR_OAUTH_TOKEN",
});

Storyblok.post(`spaces/${spaceId}/stories`, {
  story: { name: "xy", slug: "xy" },
});
Storyblok.put(`spaces/${spaceId}/stories/1`, {
  story: { name: "xy", slug: "xy" },
});
Storyblok.delete(`spaces/${spaceId}/stories/1`, null);

Using the RichTextResolver separately

You can import and use the RichTextResolver directly:

// you should need to use the format when import
// es - when you are in EsModules environment (like React, Vue apps, for example)
// cjs - when you are in NodeJS environment
// standalone - when you are in Browser environment directly

import RichTextResolver from 'storyblok-js-client/dist/rich-text-resolver.es'
// const RichTextResolver = require('storyblok-js-client/dist/rich-text-resolver.cjs')

const resolver = new RichTextResolver();

const html = resolver.render(data);

Using from the Browser directly

This package has a standalone version that contains all dependencies and you can use it to import and use our package inside the browser.

<!-- This import makes the StoryblokClient class available globally -->
<script src="https://cdn.jsdelivr.net/npm/storyblok-js-client@4.0.5/dist/index.standalone.js"></script>

<!-- This import makes the RichTextResolver class available globally -->
<script src="https://cdn.jsdelivr.net/npm/storyblok-js-client@4.0.5/dist/rich-text-resolver.standalone.js"></script>

If you want a bundle with Babel (for non-es6 browsers):

<!-- This import makes the StoryblokClient class available globally -->
<script src="https://cdn.jsdelivr.net/npm/storyblok-js-client@4.0.5/dist/es5/index.standalone.js"></script>

<!-- This import makes the RichTextResolver class available globally -->
<script src="https://cdn.jsdelivr.net/npm/storyblok-js-client@4.0.5/dist/es5/rich-text-resolver.standalone.js"></script>

Note about use of Babel

This package doesn't use the Babel by default in the final bundle. So, if you want a Babel transpiled file, you need to set the es5/ prefix on import:

// for CommonJS environments (NodeJS)
const StoryblokClient = require('storyblok-js-client/dist/es5/index.cjs')

// for EsModules environments
import StoryblokClient from 'storyblok-js-client/dist/es5/index.es'

Assets structure compatibility

We added retro-compatibility when using resolve_assets: 1 parameter under V2. Now, if you are using our V2 client, you should receive the assets structure just the same as V1.

Documentation

Class Storyblok

Parameters

• config Object
  • accessToken String, The preview token you can find in your space dashboard at https://app.storyblok.com
  • cache Object
    • type String, none or memory
  • (responseInterceptor Function, optional - You can pass a function and return the result, like axios' interceptors. For security reasons, Storyblok client will deal only with the response interceptor.)
  • (region String, optional)
  • (https Boolean, optional)
  • (rateLimit Integer, optional, defaults to 3 for management api and 5 for cdn api)
  • (timeout Integer, optional)
  • (maxRetries Integer, optional, defaults to 5)
  • (richTextSchema Object, optional - your custom schema for RichTextRenderer)
• (endpoint String, optional)

Activating request cache

The Storyblok client comes with a caching mechanism. When initializing the Storyblok client you can define a cache provider for caching the requests in memory. To clear the cache you can call Storyblok.flushCache() or activate the automatic clear with clear: 'auto'.

let Storyblok = new StoryblokClient({
  accessToken: "xf5dRMMjltLzKOcNgMaU9Att",
  cache: {
    clear: "auto",
    type: "memory",
  },
});

Passing response interceptor

The Storyblok client lets you pass a function that serves as a response interceptor to axios. Usage:

let Storyblok = new StoryblokClient({
  accessToken: "xf5dRMMjltLzKOcNgMaU9Att",
  cache: {
    clear: "auto",
    type: "memory",
  },
  responseInterceptor: (response) => {
    // one can handle status codes and more with the response
    if (response.status === 200) {
      // handle your status here
    }
    // ALWAYS return the response
    return response;
  },
});

Method Storyblok#get

With this method you can get single or multiple items. The multiple items are paginated and you will receive 25 items per page by default. If you want to get all items at once use the getAll method.

Parameters

• [return] Promise, Object response
• path String, Path (can be cdn/stories, cdn/tags, cdn/datasources, cdn/links)
• options Object, Options can be found in the API documentation.

Example

Storyblok.get("cdn/stories/home", {
  version: "draft",
})
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Method Storyblok#getAll

With this method you can get all items at once.

Parameters

• [return] Promise, Array of entities
• path String, Path (can be cdn/stories, cdn/tags, cdn/datasources, cdn/links)
• options Object, Options can be found in the API documentation.
• entity String, Storyblok entity like stories, links or datasource. It's optional.

Example

Storyblok.getAll("cdn/stories", {
  version: "draft",
})
  .then((stories) => {
    console.log(stories); // an array
  })
  .catch((error) => {
    console.log(error);
  });

Method Storyblok#post (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client)
• payload Object

Example

Storyblok
  .post('spaces/12345/stories', {
    story: {name 'xy', slug: 'xy'}
  })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#put (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-js-client)
• payload Object

Example

Storyblok
  .put('spaces/12345/stories/1', {
    story: {name 'xy', slug: 'xy'}
  })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#delete (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication)
• payload Object

Example

Storyblok.delete("spaces/12345/stories/1", null)
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Method Storyblok#flushCache

Parameters

• [return] Promise, Object returns the Storyblok client

Example

Storyblok.flushCache();

Method Storyblok#setComponentResolver

Parameters

• callback Function, Render function to render components of the richtext field

Option 1: Use a switch case definition to render different components:

Storyblok.setComponentResolver((component, blok) => {
  switch (component) {
    case "my-custom-component":
      return `<div class="my-component-class">${blok.text}</div>`;
      break;
    case "my-header":
      return `<h1 class="my-class">${blok.title}</h1>`;
      break;
    default:
      return "Resolver not defined";
  }
});

Option 2: Dynamically render a component (Example in Vue.js):

Storyblok.setComponentResolver((component, blok) => {
  return `<component :blok='${JSON.stringify(blok)}'
                     is="${component}"></component>`;
});

Method Storyblok#richTextResolver.render

Parameters

• [return] String, Rendered html of a richtext field
• data Richtext object, An object with a content (an array of nodes) field.

Example

Storyblok.richTextResolver.render(blok.richtext);

Code examples

Filter by content type values and path

const StoryblokClient = require("storyblok-js-client");

let client = new StoryblokClient({
  accessToken: "zlRONoLBKrilxkz2k6fYuwtt",
});

// Filter by boolean value in content type
client
  .get("cdn/stories", {
    version: "draft",
    filter_query: {
      is_featured: {
        in: true,
      },
    },
  })
  .then((res) => {
    console.log(res.data.stories);
  });

// Get all news and author contents
client
  .get("cdn/stories", {
    version: "draft",
    filter_query: {
      component: {
        in: "news,author",
      },
    },
  })
  .then((res) => {
    console.log(res.data.stories);
  });

// Get all content from the news folder
client
  .get("cdn/stories", {
    version: "draft",
    starts_with: "news/",
  })
  .then((res) => {
    console.log(res.data.stories);
  });

Download all content from Storyblok

Following a code example using the storyblok-js-client to backup all content on your local filesystem inside a 'backup' folder.

const StoryblokClient = require("storyblok-js-client");
const fs = require("fs");

let client = new StoryblokClient({
  accessToken: "WcdDcNgDm59K72EbsQg8Lgtt",
});

let lastPage = 1;
let getStories = (page) => {
  client
    .get("cdn/stories", {
      version: "draft",
      per_page: 25,
      page: page,
    })
    .then((res) => {
      let stories = res.data.stories;
      stories.forEach((story) => {
        fs.writeFile(
          "./backup/" + story.id + ".json",
          JSON.stringify(story),
          (err) => {
            if (err) throw err;

            console.log(story.full_slug + " backed up");
          }
        );
      });

      let total = res.total;
      lastPage = Math.ceil(res.total / res.perPage);

      if (page <= lastPage) {
        page++;
        getStories(page);
      }
    });
};

getStories(1);

Initialize with a proxy server

const proxy = {
  host: host,
  port: port,
  auth: {
    username: 'username',
    password: 'password'
  }
}

const storyblok = new StoryblokClient({
  ...
  https: false,
  proxy: proxy
})

Read more about proxy settings in axios documentation

How to define a custom schema for the RichTextRenderer

To define how to add some classes to specific html attributes rendered by the rich text renderer, you need your own schema definition. With this new schema, you can pass it as the richTextSchema option when instantiate the StoryblokClient class. You must follow the default schema to do this.

Below, you can check an example:

const StoryblokClient = require("storyblok-js-client");

// the default schema copied and updated
const MySchema = require("./my-schema");

let client = new StoryblokClient({
  accessToken: "WcdDcNgDm59K72EbsQg8Lgtt",
  richTextSchema: MySchema,
});

client.richTextResolver.render(data);

If you just want to change the way a specific tag is rendered you can import the default schema and extend it. Following an example that will render headlines with classes:

Instead of <p>Normal headline</p><h3><span class="margin-bottom-fdsafdsada">Styled headline</span></h3> it will render <p>Normal headline</p><h3 class="margin-bottom-fdsafdsada">Styled headline</h3>.

const RichTextResolver = require("storyblok-js-client/dist/richTextResolver");
const MySchema = require("storyblok-js-client/dist/schema");

MySchema.nodes.heading = function (node) {
  let attrs = {};

  if (
    node.content &&
    node.content.length === 1 &&
    node.content[0].marks &&
    node.content[0].marks.length === 1 &&
    node.content[0].marks[0].type === "styled"
  ) {
    attrs = node.content[0].marks[0].attrs;
    delete node.content[0].marks;
  }

  return {
    tag: [
      {
        tag: `h${node.attrs.level}`,
        attrs: attrs,
      },
    ],
  };
};

let rteResolver = new RichTextResolver(MySchema);
let rendered = rteResolver.render({
  content: [
    {
      content: [
        {
          text: "Normal headline",
          type: "text",
        },
      ],
      type: "paragraph",
    },
    {
      attrs: {
        level: 3,
      },
      content: [
        {
          marks: [
            {
              attrs: {
                class: "margin-bottom-fdsafdsada",
              },
              type: "styled",
            },
          ],
          text: "Styled headline",
          type: "text",
        },
      ],
      type: "heading",
    },
  ],
  type: "doc",
});

console.log(rendered);

🔗 Related Links

• Storyblok & Javascript on GitHub: Check all of our Javascript open source repos;
• Technology Hub: We prepared technology hubs so that you can find selected beginner tutorials, videos, boilerplates, and even cheatsheets all in one place;
• Storyblok CLI: A simple CLI for scaffolding Storyblok projects and fieldtypes.

ℹ️ More Resources

Support

• Bugs or Feature Requests? Submit an issue;

• Do you have questions about Storyblok or you need help? Join our Discord Community.

Contributing

Please see our contributing guidelines and our code of conduct. This project use semantic-release for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check this question about it in semantic-release FAQ.